Skip Headers

Oracle® Database Backup and Recovery Advanced User's Guide 10g Release 2 (10.2) Part Number B14191-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# Working with RMAN Stored Scripts in the Recovery Catalog

Stored scripts offer an alternative to command files for managing frequently used sequences of RMAN commands.

The chief advantage of a stored script over a command file is that a stored script is always available to any RMAN client that can connect to the target database and recovery catalog, whereas command files are only available if the RMAN client has access to the file system on which they are stored.

Stored scripts can be global or local. A local stored script is associated with the target database to which RMAN is connected when the script is created, and can only be executed when you are connected to that target database. A global stored script can be run against any database registered in the recovery catalog, if the RMAN client is connected to the recovery catalog and a target database.

Note that to work with stored scripts, even global ones, you must be connected to both a recovery catalog and a target instance.

## Creating Stored Scripts: CREATE SCRIPT

Make sure RMAN is connected to the right target database and the recovery catalog. Then run the `CREATE` `SCRIPT` command, as shown in this example:

    CREATE SCRIPT full_backup
    {
      BACKUP DATABASE PLUS ARCHIVELOG;
      DELETE OBSOLETE;
    }

Examine the output. If no errors are displayed, then the script was successfully created and stored in the recovery catalog.

For a global script, the syntax is similar:

    CREATE GLOBAL SCRIPT global_full_backup
    {
      BACKUP DATABASE PLUS ARCHIVELOG;
      DELETE OBSOLETE;
    }

You can also provide a `COMMENT` with descriptive information:

    CREATE GLOBAL SCRIPT global_full_backup
    COMMENT 'use only with ARCHIVELOG mode databases'
    {
      BACKUP DATABASE PLUS ARCHIVELOG;
      DELETE OBSOLETE;
    }

Finally, you can create a local or global script, reading its contents from a text file:

    CREATE SCRIPT full_backup FROM FILE 'my_script_file.txt';

The file must begin with a `{` character, contain a series of commands valid within a RUN block, and end with a `}` character. Otherwise, a syntax error is signalled, just as if the commands were entered at the keyboard.

## Running Stored Scripts: EXECUTE SCRIPT

To run a stored script, connect to the target database and recovery catalog, and use `EXECUTE` `SCRIPT`. `EXECUTE SCRIPT` requires a `RUN` block, as shown:

    RUN { EXECUTE SCRIPT full_backup; }

This command invokes a local script if one is with the name specified. If no local script is found, but there is a global script with the name specified, RMAN will execute the global script. You can also use `EXECUTE GLOBAL SCRIPT` to control which script is invoked if a local and a global script have the same name. Assuming there is no local script called `global_full_backup`, the following two commands have the same effect:

    RUN { EXECUTE GLOBAL SCRIPT global_full_backup; }
    RUN { EXECUTE SCRIPT global_full_backup; }

Executing a global script only affects the connected target database; to run a global script across multiple databases, you must connect the RMAN client to each one separately and execute the script.

Your script will use the automatic channels configured at the time you execute the script. Use `ALLOCATE` `CHANNEL` commands in the script if you need to override the configured channels. Note that, because of the RUN block, if an RMAN command in the script fails, subsequent RMAN commands in the script will not execute.

See Also: Oracle Database Backup and Recovery Reference for `EXECUTE` `SCRIPT` command syntax

## Displaying a Stored Script: PRINT SCRIPT

The `PRINT` `SCRIPT` command displays a stored script or writes it out to a file. With RMAN connected to the target database and recovery catalog, use the PRINT SCRIPT command as shown here:

    PRINT SCRIPT full_backup;

To send the contents of a script to a file, use this form of the command:

    PRINT SCRIPT full_backup TO FILE 'my_script_file.txt';

For global scripts, the analogous syntax would be:

    PRINT GLOBAL SCRIPT global_full_backup;

and

    PRINT GLOBAL SCRIPT global_full_backup TO FILE 'my_script_file.txt';

See Also: Oracle Database Backup and Recovery Reference for `PRINT` `SCRIPT` command syntax

## Listing Stored Scripts: LIST SCRIPT NAMES

Use the `LIST SCRIPT NAMES` command to display the names of scripts defined in the recovery catalog. This command displays the names of all stored scripts, both global and local, that can be executed for the currently connected target database:

    LIST SCRIPT NAMES;

If RMAN is not connected to a target database when the `LIST` `SCRIPT` `NAMES` command is run, then RMAN will respond with an error.

To view only global script names, use this form of the command:

    LIST GLOBAL SCRIPT NAMES;

To view the names of all scripts stored in the current recovery catalog, including global scripts and local scripts for all target databases registered in the recovery catalog, use this form of the command:

    LIST ALL SCRIPT NAMES;

The output will indicate for each script listed which target database the script is defined for (or whether a script is global).

Note: `LIST GLOBAL SCRIPT NAMES` and `LIST ALL SCRIPT NAMES` are the only commands that work when RMAN is connected to a recovery catalog without connecting to a target instance.

See Also: Oracle Database Backup and Recovery Reference for `LIST` `SCRIPT NAMES` command syntax and output format.

## Updating Stored Scripts: REPLACE SCRIPT

To update stored scripts, connect to the target database and recovery catalog and use the `REPLACE` `SCRIPT` command. If the script does not already exist, then RMAN creates it.

This command updates stored script script `full_backup` with new contents:

    REPLACE SCRIPT full_backup
    {
      BACKUP DATABASE PLUS ARCHIVELOG;
    }

Global scripts can be updated using the `REPLACE GLOBAL SCRIPT` command when connected to a recovery catalog, as follows:

    REPLACE GLOBAL SCRIPT global_full_backup
    COMMENT 'A script for full backup to be used with any database'
    {
      BACKUP AS BACKUPSET DATABASE PLUS ARCHIVELOG;
    }

As with `CREATE SCRIPT`, you can update a local or global stored script from a text file, with this form of the command:

    REPLACE GLOBAL SCRIPT global_full_backup FROM FILE 'my_script_file.txt';

See Also: Oracle Database Backup and Recovery Reference for `REPLACE` `SCRIPT` command syntax

## Deleting Stored Scripts: DELETE SCRIPT

To delete a stored script from the recovery catalog, connect to the catalog and a target database, and use the `DELETE` `SCRIPT` command:

    DELETE SCRIPT 'full_backup';

To delete a global stored script, use `DELETE GLOBAL SCRIPT`:

    DELETE GLOBAL SCRIPT 'global_full_backup';

If you use `DELETE SCRIPT` without `GLOBAL`, and there is no stored script for the target database with the specified name, RMAN will look for a global stored script by the specified name and delete the global script if it exists. So, if you were to enter the command

    DELETE SCRIPT 'global_full_backup';

RMAN would look for a script '`global_full_backup`' defined for the connected target database, and if it did not find one, it would search the global scripts for a script called '`global_full_backup`' and delete that script.

See Also: Oracle Database Backup and Recovery Reference for `DELETE` `SCRIPT` command syntax

## Starting the RMAN Client and Running a Stored Script

To run the RMAN client and start a stored script in the recovery catalog on startup, use the `SCRIPT` argument when starting the RMAN client.

    % rman TARGET SYS/oracle@trgt CATALOG rman/cat@catdb SCRIPT 'full_backup';

You must connect to a recovery catalog (which contains the stored script) and target database (to which the script will apply) when starting the RMAN client.

See Also: Oracle Database Backup and Recovery Reference for full RMAN client command line syntax

## Restrictions on Stored Script Names

There are some issues to be aware of about how RMAN resolves script names, especially when a local and global script share the same name.

- RMAN permits but generally does not require that you use quotes around the name of a stored script. However, if the name begins with a digit or if the name is an RMAN reserved word, you will have to put quotes around the name to use it as a stored script name. Consider avoiding stored script names that begin with characters other than A-Z or that are the same as RMAN reserved words.

  See Also: Oracle Database Backup and Recovery Reference

- When starting the RMAN client with a SCRIPT argument on the command line, if local and global scripts are defined with the same name, then RMAN will always execute the local script.

- For the `EXECUTE SCRIPT`, `DELETE SCRIPT` and `PRINT SCRIPT` commands, if the script name passed as an argument is not the name of a script defined for the connected target instance, RMAN will look for a global script by the same name to execute, delete or print. For example, if the a stored script `global_full_backup` is in the recovery catalog as a global script, but no local stored script `global_full_backup` is defined for the target database, the following command will delete the global script:

      DELETE SCRIPT global_full_backup;

Consider using some naming convetion to avoid mistakes due to confusion between global stored scripts and local stored scripts.

See Also: Oracle Database Backup and Recovery Reference for the list of RMAN reserved words.